Risc World 3/Risc World 3.iso/SOFTWARE/ISSUE4/ZAP/!Zap/Modules/!ZapSAsm/!Help

Text File | 2002-05-08 | 15KB | 351 lines

 ____________________                       ____________________
 ¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨ ##| ##|  ######|  ##|    #####| ¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨
              ##| ##|  ##|¯¯¯    ##|    ##|¯##|
              ##| ##|  ##|    ##|    ##| ##|
              ######|  #####|    ##|    #####|
              ##|¯##|  ##|¯¯    ##|    ##|¯¯
              ##| ##|  ##|    ##|    ##|
 ____________________ ##| ##|  ######|  #####|  ##| _______________________
 ¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨ ¯¯  ¯¯   ¯¯¯¯¯¯    ¯¯¯¯¯    ¯¯  ¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨
 ——————————————————————————————————————————————————————————————————————————
   ZapSAsm                       Version 1.04 (21 May 1995)
 ——————————————————————————————————————————————————————————————————————————
       This application is © 1995 James Freeman. All Rights Reserved.

          It is FREEWARE. Use is at your own risk.
         Please read the conditions at the end of this file.

 −−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−
  G E N E R A L      I N F O R M A T I O N
 ——————————————————————————————————————————————————————————————————————————
         Sattinger’s Law: It works better if you plug it in.
 ––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––– Arthur Bloch

 Program:  ZapSAsm

 Purpose:  Extension mode and utilities for Zap.

 Requires: Tested on RISC OS 3.1x and later.
        (Read: it may work on RISC OS 2, but then again...)
       Zap 1.23 or later.
        (ZapSAsm will function with Zap 1.20 but, because of a little
        bug in Zap, two of the colours will be incorrectly rendered.)

 Features: • Module takes up only 4980 bytes.
       • Hand-written in ARM code.
       • Text-based colour extension mode for SAsm source files.
       • Several mode-independent Zap commands.
       • Links Zap with WordWorks (not included :-).


 −−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−
  W H O ?   W H A T ?    W H E N ?   H O W ?
 ——————————————————————————————————————————————————————————————————————————
       It ain’t what a man don’t know that makes him a fool,
            but what he does know that ain’t so.
 –––––––––––––––––––––––––––––––––––––––––––––––––––––––––––– Josh Billings

 This program was written in ARM using Zap 1·25 and SAsm 1·60. My thanks
 to Dominic Symes (now, remind me, who’s that bloke again and what’s he
 written that everyone’s fussing over?) and David Radford for putting
 these programs into the public domain.  SAsm is shareware and written
 by David Holden.

 I give no guarantee that this program will work correctly on all machines
 and all configurations - but it works for me.  Take it or leave it.


 −−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−
  S U M M A R Y
 ——————————————————————————————————————————————————————————————————————————
          Nothing is so useless as a general maxim.
 –––––––––––––––––––––––––––––––––––––––––––––––––––––––––– Thomas Macaulay

 This directory contains:

 !Help.*                   Help text and reader.
 DemoText                   Demonstration text.
 Impulse                   Impulse methods (text).
 ZapSAsm                   Extension module.

 So, you’ve seen a colour Acorn C mode on Zap.
 Oh, and a colour BASIC mode.
 And you’ve seen a colour Acorn Assembler mode.
 But have you seen a colour SAsm mode?  No?  Guess what this is.

 If you’ve got David Holden’s excellent SAsm assembler, then this mode’s
 for you.  If you haven’t, then hold your horses - there are a few commands
 you might find useful instead, as well as support for CC’s WordWorks.

 For installation instructions, go down right to the end of this section.


 THE EXTENSION MODE
 ==================

 The SAsm mode provides the following additional colours:

  • Labels
    Definitions (ie. ‘.labelname’) - not references from (eg.) branches.

  • Macros
    Both expanded macro and macro function calls are recognised.

  • Immediates
    Only if preceded by hash (‘#’).  This means that the enhanced second
    operand feature of SAsm (for ‘CMP’, ‘MOV’, ‘TST’ and ‘TEQ’) is not
    recognised.  (The reason it isn’t currently implemented is because it
    only applies to those four mnemonics; I’ve already written the code for
    it, but it operates on all the second operands...)  In addition, the
    equates ‘EQUB’, ‘EQUW’, ‘EQUD’, ‘EQUS’, ‘DCB’, ‘DCW’, ‘DCD’, ‘DB’,
    ‘DW’, and ‘DB’ are recognised as being followed by an immediate
    constant.

  • Strings
    Anything within double quotation marks which isn’t a comment.

  • Comments
    Both ‘;’ (with checks, to allow ‘#PRINT"blah";’) and ‘\’ are supported.
    I do not recognise ‘REM’.  (You honestly don’t use this for assembler
    do you?  Oh dearie me...  If anyone requests, I’ll probably add it.)

  • Directives
    And lines passed to BASIC (ie. lines which begin with a hash).

  • Operands1
    Anything after the mnemonic which isn’t an immediate, string, comment
    or displayed in the ‘Operands2’ colour.

  • Operands2
    The following characters within the operand are displayed in this
    colour: ‘[’, ‘]’, ‘{’, ‘}’, ‘(’, ‘)’, ‘!’, ‘^’, ‘-’ and ‘,’.

  • Shifts
    Now, and as if you couldn’t guess, the shifts (that’s ‘LSL’, ‘LSR’,
    ‘ASL’, ‘ASR’, ‘ROR’ and ‘RRX’ in case you didn’t realise) are displayed
    in this colour.

 Remember though: just because you’ve got so many *logical* colours doesn’t
 mean they all have to be different *physical* colours.  Of course, if you
 like your source code looking like a rainbow, that’s your decision :-)

 And another thing: SAsm should produce proper colours for SAsm source
 textfiles.  If you load non-SAsm sources, etc, you are likely to find that
 the colouring goes a bit awry.  Remember, it is expecting text in the
 correct syntax for SAsm.  (Oh really?)


 STILL TO BE IMPLEMENTED
 =======================

  • Enhanced second operand detection for CMP/MOV/TEQ/TST.

  • REM recognition.

  • SWI name processing (#swion).

  • Non-local labels allowed after colons.

  • Multi-line features (very difficult!): {} comments, #end, #area.


 PROBLEMS / FUTURE PLANS
 =======================

  • With lines longer than the width of the window, the part(s) which wrap
    round are not coloured correctly.

  • There’s also a problem if the text goes right up to the right hand side
    of the window.


 OTHER FEATURES OF THE SASM MODE
 ===============================

 The following are entry points for the SAsm mode:

  • The ‘COMPILE’ and ‘SAVEANDRUN’ entry points save the source file you’re
    editing and run the file ‘!!Make’ in the same directory as the source.
    (Hint: I use a TaskObey (&FD7) file which *REMOVEs any error files etc,
    then runs SAsm giving it the filename of the ‘!Make’ file in the same
    directory - this second file is a textfile consisting of various
    directives (eg. #VERBOSE, #ERRFILE) and then a list of #INCLUDEs for
    my source files, constants files and function definition files.)

  • The ‘RUN’ and ‘RUNANDQUIT’ entry points run the ‘!!Make’ file without
    first saving the source.  (Provided for completeness because it was
    very easy to do .. I don’t know what you’d need it for though.)

BTW - the mode sets ‘SAsm$Dir’ to the directory containing ‘!!Make’.

  • The ‘LISTFNS’ entry point searches for all uncommented expanded macros
    and macro function definitions.  It simply begins a search for the
    string ‘\<\(\I\|\&20\)\*\(\&23\( \)\*\-sm\|\+DEF\( \)\*\+FN\)’.

 Given the way SAsm handles wildcarded source filenames, you will probably
 find the ‘DECANDSAVE’ command (below) useful.  (I use it all the time.)


 COMMUNICATING WITH WORDWORKS
 ============================

 While Computer Concepts’ Impulse module is installed, the following
 features are available from ZapSAsm:

  • The command ‘WORDWORKS’ sends the Impulse method ‘NewRegion’ together
    with the current selection (in Zap) to all Impulse tasks.  If you have
    Computer Concepts’ WordWorks application loaded, this message is
    recognised by it, and it will try to find the word/phrase in the
    dictionary/thesaurus.  If there is no selection in Zap, this command
    will have no effect.

  • ZapSAsm supports the Impulse method ‘Enter’ (sent by WordWorks), which
    enters the supplied text into the current window.  If there is a
    selection in Zap in the same *file* as the current window (but not
    necessarily the same window), the text replaces the selected text.

 Note that ZapSAsm is not ‘intelligent’, in the sense that it will not
 check your grammar!  That is to say - if you send ‘enters’ to WordWorks,
 it will bring up a display on ‘enter’; if you then choose the alternative
 word ‘insert’ from the thesaurus and replace it in your Zap document, it
 puts ‘insert’ there - and not ‘inserts’.


 OTHER COMMANDS
 ==============

 The following are commands available from any mode:

  • The ‘INCVERSION’ command increments the version number of the current
    file.  In other words, if the leafname is ‘Source5’ then it’s changed
    to ‘Source6’.  This wraps round, so ‘File9’ becomes ‘File0’ (rather
    than ‘File10’).

  • The ‘INCANDSAVE’ command increments the version number of the current
    file and then saves it under the new filename.

  • The ‘DECVERSION’ command decrements the version number of the current
    file.  In other words, if the leafname is ‘Source35’ then it’s changed
    to ‘Source34’.  This wraps round, so ‘File000’ becomes ‘File999’.

  • The ‘DECANDSAVE’ command decrements the version number of the current
    file and then saves it under the new filename.

  • The ‘LOSECARET’ command removes the caret from Zap.

  • The ‘LISTLABELS’ command searches for uncommented labels in the current
    file.  It simply begins a search for the string ‘\<\( \|\I\)\*.\.\.\*’.

  • The ‘WOSCLI’ command sends its string parameter to OS_CLI (via
    Wimp_StartTask).  (Note that Zap’s ‘OSCLI’ command works differently;
    it sends the *command’s output to a scrapfile, then opens a window on
    that file.  ‘WOSCLI’ on the other hand just shows any vdu output in
    a regular non-multi-tasking Wimp command window.)



 INSTALLATION
 ============

 Copy the !ZapSAsm application into the !Zap.Modules directory, then
 restart Zap.

 −−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−
  P R O G R A M      H I S T O R Y
 ——————————————————————————————————————————————————————————————————————————
         The World Record holder for blowing a bugle whilst
          riding a bike uphill dragging four hundredweight
         of pig iron and holding his breath is buried at...
 ––––––––––––––––––––––––––––––––––––––––––––––––––––––––––– Spike Milligan

 1.00 First version for Zap 1·20.
 1.01 A few bug fixes later.  It might just work :-)
 1.02 No, it most definitely won’t :-(  And I’m just doing a couple of bug
      fixes when I notice my text-wrapping problem (see above).  Aaargh!
      OK, it’s way from perfect, but it’ll have to suffice for a while.
 1.03 But it only sufficed for a very little while.  Fingers crossed...
 1.04 Another bug fixed after testing with Zap 1.27...
      FIRST RELEASE VERSION, emailed to Dom.


 −−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−
  L A S T   W O R D S
 ——————————————————————————————————————————————————————————————————————————
       Die, my dear doctor? That’s the last thing I shall do.
 ––––––––––––––––––––––––––––––––––––––––––––––––– Lord Palmerston (Attrib)

  • IMPORTANT legal notes: please read.  If you cannot comply with the
    following, please delete this software package immediately.
    —−—−—−—−—−—−—−—−—−—−—−—−—−—−—−—−—−—−—−—−—−—−—−—−—−—−—−—−—−—−—−—−—−—−—−—
    (1) Definitions:
    'Package' means the 'ZapSAsm' module and all the files connected with
    this module.
    'The Author' means Mr James P Freeman.
    'Freeware' means freely distributable in the sense that no profit is
    made from the distribution of the package, and that the contents of the
    package remain the copyright of the relevant author(s).  The extent to
    which the contents are copyright The Author is given in section (2).
    —−—−—−—−—−—−—−—−—−—−—−—−—−—−—−—−—−—−—−—−—−—−—−—−—−—−—−—−—−—−—−—−—−—−—−—
    (2) Extent:
    All files within this package are © copyright The Author.
    The exception(s) above is/are subject to the same distribution
    conditions unless stated otherwise here or elsewhere: in other words,
    it/they should be distributed alongside the The Author's files.
    —−—−—−—−—−—−—−—−—−—−—−—−—−—−—−—−—−—−—−—−—−—−—−—−—−—−—−—−—−—−—−—−—−—−—−—
    (3) Distribution conditions:
    This package is Freeware.  You may give a copy to anyone but there must
    be no charge.  For so-called 'Public Domain' and 'Shareware' libraries,
    a small fee for the cost of discs, postage and administration is
    allowed, provided that the cost of the disc upon which this package is
    included is NOT MORE THAN UK£1·75 for an 800K disc, or £2·50 for a
    1600K disc.  This package must be distributed in a COMPLETE and
    UNALTERED state.  Distribution on a magazine disc or other than as
    described here may only be undertaken with The Author's express advance
    written permission.
    —−—−—−—−—−—−—−—−—−—−—−—−—−—−—−—−—−—−—−—−—−—−—−—−—−—−—−—−—−—−—−—−—−—−—−—
    (3a) Special distribution conditions:
    Although this package may be copied alone subject to the above terms,
    it is specifically designed to be internal to Dominic Symes' Zap
    editor.  Where it is supplied with Zap, that application's distribution
    conditions apply and section (3) should be construed so as to accord
    with those conditions.  If any part of section (3) is inconsistent with
    those conditions, the latter prevail.
    —−—−—−—−—−—−—−—−—−—−—−—−—−—−—−—−—−—−—−—−—−—−—−—−—−—−—−—−—−—−—−—−—−—−—−—
    (4) Other conditions:
    THIS PACKAGE IS SUPPLIED 'AS IS'.  USE IS ENTIRELY AT THE USER'S OWN
    RISK.  It carries no warranty, express or implied.  No guarantee is
    given of even the implied terms of satisfactory quality or suitability
    for purpose.  The Author accepts no responsibility whatsoever for this
    package and under no circumstances will be liable, in negligence or
    otherwise, for any damage (whether physical or economic), including but
    not restricted to direct, incidental and consequential loss, arising
    through, or in any way connected with, the use or misuse of this
    package or any files or routines contained therein - even if The Author
    has been advised of the possibility of such loss.  The Author reserves
    the right to amend this notice and/or alter the distribution conditions
    of this software package at any time.
    —−—−—−—−—−—−—−—−—−—−—−—−—−—−—−—−—−—−—−—−—−—−—−—−—−—−—−—−—−—−—−—−—−—−—−—

  • PLEASE NOTE THAT THIS PROGRAM IS NOT PUBLIC DOMAIN.

    Any bug reports or missing commands should be sent to

        [e-mail]

    Feature requests should be directed towards

          [e-mail]


There are a also a number of mailing lists you can subscribe to - see
Zap's web pages for details:

        http://zap.tartarus.org/


 −−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−
  E R R A T U M
 ——————————————————————————————————————————————————————————————————————————
          This slip has been inserted by mistake.
 –––––––––––––––––––––––––––––––––––––––––––––––––––––––––––– Alisdair Gray